=begin pod

=TITLE class Backtrace

=SUBTITLE Snapshot of the dynamic call stack

    class Backtrace is List {}

A backtrace shows the dynamic call stack, usually leading up to a point
where an exception was thrown.

It is a List of L<Backtrace::Frame> objects.  Its default stringification
excludes backtrace frames that are deemed unnecessary or confusing, for
example routines like C<&die> are hidden by default.

=head1 Methods

=head2 method new

Defined as:

    multi method new(--> Backtrace:D)

Creates a new backtrace, using its calling location as the origin of the
backtrace.

    my $backtrace = Backtrace.new;

=head2 method gist

Defined as:

    multi method gist(Backtrace:D: --> Str:D)

Returns string C<"Backtrace(42 frames)"> where the number indicates the number
of frames available via L<list> method.

=head2 method Str

Defined as:

    multi method Str(Backtrace:D:)

Returns a concise string representation of the backtrace, omitting
routines marked as C<is hidden-from-backtrace>, and at the discretion of
the implementation, also some routines from the setting.

    my $backtrace = Backtrace.new;
    say $backtrace.Str;

=head2 method full

Defined as:

    multi method full(Backtrace:D:)

Returns a full string representation of the backtrace, including hidden
frames, compiler-specific frames and those from the setting.

    my $backtrace = Backtrace.new;
    say $backtrace.full;

=head2 method list

Defined as:

    multi method list(Backtrace:D:)

Returns a list of L<Backtrace::Frame> objects for this backtrace.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
